NetLogo User Community Models

(back to the NetLogo User Community Models)

Download If clicking does not initiate a download, try right clicking or control clicking and choosing "Save" or "Download".(The run link is disabled because this model uses external files.)

# OVERVIEW

This simulation model was designed to simulate population dynamics and the evolution of the **boundary-crossing response** in a landscape context. The **boundary-crossing response** is the tendency to cross habitat boundaries, i.e. when a dispersing individual encounters a habitat boundary, does it turn back into habitat, or cross into non-habitat (also called 'matrix')?

The landscape context is determined by the values for four landscape attributes:

1. **habitat amount**: the proportion of the grid cells in habitat; smaller values mean less habitat

1. **habitat fragmentation**: the level of patchiness of habitat, for a given habitat amount, modeled as the Hurst exponent of the midpoint displacement algorithm used to assign locations of habitat and matrix cells (Saupe 1988); smaller values produce more fragmented habitat

1. **matrix quality**: probability of mortality during movement across a matrix cell; smaller values indicate higher matrix quality

1. **disturbance frequency**: mean number of generations until local population extinction (i.e. death of all individuals in a given habitat patch), for a Poisson distribution; smaller values indicate more frequent disturbance

Because the boundary-crossing response likely evolves along with other dispersal characteristics, the model includes three additional dispersal characteristics. All four dispersal characteristics can evolve, because each is modeled as a heritable trait:

1. **probability of boundary crossing**: probability that the individual will cross from habitat to matrix, when it encounters a boundary

1. **dispersal propensity**: probability that the individual leaves its natal habitat cell and disperses

1. **path shape in matrix**: correlation in movement direction between successive movement steps originating in matrix, modeled as the concentration parameter for a wrapped Cauchy distribution with a mean of zero

1. **path shape in habitat**: correlation in movement direction between successive movement steps originating in habitat, modeled as the concentration parameter for a wrapped Cauchy distribution with a mean of zero

Note that we use **habitat cell** and **matrix cell** when referring to a single habitat or matrix cell, respectively. **Habitat patch** refers to a contiguous group of habitat cells surrounded by matrix, where habitat cells are grouped based on a Moore (8-neighbor) neighborhood rule.

For full details, see Martin and Fahrig (2015).

##HOW TO CITE

We ask that you cite both our peer-reviewed paper and the NetLogo software:

* Amanda E. Martin and Lenore Fahrig. _In press_. Matrix quality and disturbance frequency drive evolution of species behavior at habitat boundaries. Ecology and Evolution. doi: 10.1002/ece3.1841

* Wilensky, U. (1999). NetLogo. http://ccl.northwestern.edu/netlogo/. Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL

##COPYRIGHT NOTICE

Copyright 2015 Amanda E. Martin. All rights reserved.

Permission to use, modify, or redistribute this model is granted, provided that:

* this copyright notice is included, and

* this model is not redistributed for profit

See http://creativecommons.org/licenses/by/3.0/ for details of the copyright associated with the published paper.

# MODEL STRUCTURE

A **simulation run** is initiated by creating an artificial landscape and populating it with individuals, each with a random value for its initial heritable probability of boundary crossing, dispersal propensity, path shape in matrix, and path shape in habitat. A simulation run continues for a user-specified number of generations, or until the population goes extinct.

Each generation involves:

1. **habitat disturbance**, resulting in some local population extinctions

1. **density-dependent reproduction**, including transfer of genetic information

1. **dispersal**, i.e. movement of individuals from their birth place, resulting in either dispersal mortality or settlement in a new location

# MODEL INTERFACE

## MAIN ACTIONS
* **set-up**: prepares for a simulation run; must be pressed prior to the model run

* **run-model**: runs a single simulation run, for a user-defined number of generations

##OUTPUT CONTROLS

* **save-output**: ON = model output is saved to a space-delimited plain text file, adding a row to the file (specified by **output-file-name**) in each simulated generation (see **MODEL OUTPUT** below); OFF = no data are saved

* **save-final-generation**: ON = data for the landscape and population after the final generation are saved to space-delimited plain text files, at the end of a simulation run (see **MODEL OUTPUT** below); OFF = no data are saved

* **file-directory**: path to a directory and folder where data can be saved

* **output-file-name**: name of the text file where model output is saved (for **save-output**)

* **run-id**: numerical id for a simulation run; you must use a unique value for each simulation run you save to a given folder

##MODEL PARAMETERS
The set of user-defined model parameters.

_The user must pay attention to the accepted range of values for each parameter (defined in brackets, below). If any parameter value is outside its accepted range, the model run will stop, and a message identifying the problem parameter(s) will be printed to the 'Command Center'._

###Constants
These parameter values remain constant, at the user-defined values, for each simulation run:

* **generations**: number of simulated generations (>=1)

* **lambda**: variable in the equation used to calculate the mean number of offspring produced by each adult inhabiting a habitat cell (Hassell 1975) (>=1)

* **carring-capacity**: variable in the equation used to calculate the mean number of offspring produced by each adult inhabiting a habitat cell (Hassell 1975); also determines whether a dispersing individual settles or continues moving (it can only settle if the habitat cell is below capacity) (>=1)

* **habitat-cost**: probability of mortality during movement across a habitat cell (0 - 1)

* **competition-type**: variable in the equation used to calculate the mean number of offspring produced by each adult inhabiting a habitat cell (Hassell 1975); 1 = contest competition, >1 = scramble competition (>= 1)

* **mutation-rate**: probability of mutation for a given dispersal characteristic (0 - 1)

* **mutation-increment**: change in the value of a dispersal characteristic, when mutation occurs (0 - 0.5)

###Landscape attributes
For these parameters, the model randomly selects a value for each landscape attribute in each simulation run, based on the user-defined ranges:

* **minimum-** and **maximum-habitat-amount**: defines the range of values for habitat amount (>0 - 1)

* **minimum-** and **maximum-fragmentation**: defines the range of values for habitat fragmentation (0 - 1)

* **minimum-** and **maximum-matrix-cost**: defines the range of values for matrix quality (0 - 1)

* **minimum-** and **maximum-disturbance-interval**: defines the range of values for the disturbance parameter (>=1)

##VISUAL OUTPUT
Onscreen output includes:

* the current simulation value for each of the four landscape attributes

* the simulated grid landscape (green = habitat, black = matrix) and population (yellow)

* a plot of the total population size at each generation

* a plot of the population mean trait value for each of the four dispersal characteristics in each generation

# MODEL OUTPUT

## SAVE-OUTPUT
Saves the following, for each generation of a simulation run:

* **simulation id**: unique identifier for a simulation run, as defined by **run-id**

* **generation**: generation of the simulation run

* **model parameters**: values for model parameters (see MODEL PARAMETERS above)

* **population sizes**: number of individuals in the landscape pre- and post-dispersal

* **rate of boundary crossing**: proportion of the population that crossed from habitat to matrix

* **dispersal characteristics**: the population mean and variance for each of the four, heritable dispersal characteristics: (1) probability of boundary crossing, (2) dispersal propensity, (3) path shape in matrix, and (4) path shape in habitat

A row is added to the file (specified by **output-file-name**) in each simulated generation.

## SAVE-FINAL-GENERATION

Saves two space-delimited plain text files after the final simulated generation, with detailed population data (**run_#_population.txt**) and landscape data (**run_#_landscape.txt**) [# = run-id].

### Population

Saves the location (x and y coordinates), heading, and evolved dispersal characteristics (probability of boundary crossing, dispersal propensity, path shape in matrix, and path shape in habitat) for each individual.

### Landscape

Saves the location (x and y coordinates), cell color (habitat = numeric color code 55, matrix = code 0), dispersal cost (with a different cost associated with habitat and matrix cells), time to disturbance, and unique habitat patch ID (identifies which habitat cells belong to each habitat patch), for each grid cell.

## ADDITIONAL REFERENCES

Hassell, M. P. (1975). Density-dependence in single-species populations. Journal of Animal Ecology, 44:283–295. doi: 10.1016/0022-5193(80)90297-0.

Saupe, D. (1988). Algorithms for random fractals. _Pages_ 71–136 _in_ Peitgen, H.-O. and Saupe, D. (eds) The Science of Fractal Images. Springer-Verlag, New York.